<!DOCTYPE html>

<html lang="en" data-content_root="../../">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

    <title>Sprites &#8212; Pytch  documentation</title>
    <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=03e43079" />
    <link rel="stylesheet" type="text/css" href="../../_static/classic.css?v=36340f97" />
    <link rel="stylesheet" type="text/css" href="../../_static/css/pytch-classic.css?v=0321735e" />
    
    <script src="../../_static/documentation_options.js?v=7f41d439"></script>
    <script src="../../_static/doctools.js?v=9bcbadda"></script>
    <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
    
    <link rel="icon" href="../../_static/favicon.ico"/>
    <link rel="author" title="About these documents" href="../../about.html" />
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="The stage" href="stage.html" />
    <link rel="prev" title="Writing Pytch programs" href="index.html" /> 
  </head><body>
<div class="NavBar">
  <a href="../../../app/"><h1>Pytch</h1></a>
  <ul>
    <a href="https://pytch.scss.tcd.ie/"><li>About Pytch</li></a>
    <a href="../../index.html"><li>Help</li></a>
    <a href="../../../app/tutorials/"><li>Tutorials</li></a>
    <a href="../../../app/my-projects/"><li>My projects</li></a>
  </ul>
</div>
<div class="warning-work-in-progress">
  <p>These help pages are incomplete — we are working on it!</p>
</div>
  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <section id="sprites">
<h1>Sprites<a class="headerlink" href="#sprites" title="Link to this heading">¶</a></h1>
<p>Sprites are the things in a project that appear on the stage, move
about, and generally perform actions. Most projects will have at least
one sprite.</p>
<p>You control how a sprite moves and acts by writing <em>scripts</em>. Each
sprite can also have <em>costumes</em> and <em>sounds</em> that control how it looks
and sounds.</p>
<p>Each sprite has <em>methods</em> which are commands that you can issue to get a
sprite to do something.  You also write your own methods to say how your
sprite should behave, in two ways:</p>
<ul class="simple">
<li><p>A method which should run every time some event happens, for example
when the green flag is clicked.  See <a class="reference internal" href="hat-blocks.html"><span class="doc">Scratch hat blocks → Pytch decorators</span></a> for details of
how this works.</p></li>
<li><p>A method which your code will use internally.  These are the
equivalent of the <em>custom blocks</em> you can define in Scratch.</p></li>
</ul>
<section id="creating-sprites">
<h2>Creating Sprites<a class="headerlink" href="#creating-sprites" title="Link to this heading">¶</a></h2>
<p>You can create a Sprite in your project by declaring a Python <em>class</em>
that uses the Sprite as a foundation. You do this by creating a class
with some name (for example, “Kitten”), and mentioning the pytch Sprite
class as its basis. Here is an example of a Kitten class that has a
single costume (costumes are discussed just below):</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pytch</span>

<span class="k">class</span><span class="w"> </span><span class="nc">Kitten</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="n">Costumes</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;happy-kitten.jpg&quot;</span><span class="p">]</span>
</pre></div>
</div>
</section>
<section id="saying-how-a-sprite-should-behave">
<h2>Saying how a sprite should behave<a class="headerlink" href="#saying-how-a-sprite-should-behave" title="Link to this heading">¶</a></h2>
<p>In Scratch you put together scripts which say how you want your Sprite
to behave when certain things happen, for example, when that Sprite is
clicked.  In Pytch, you do this by writing your own methods on your
class.  For example,</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">pytch</span>

<span class="k">class</span><span class="w"> </span><span class="nc">Spaceship</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="nd">@pytch</span><span class="o">.</span><span class="n">when_key_pressed</span><span class="p">(</span><span class="s2">&quot;ArrowUp&quot;</span><span class="p">)</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">move_up</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">change_y</span><span class="p">(</span><span class="mi">10</span><span class="p">)</span>
</pre></div>
</div>
<p>Here we see:</p>
<ul class="simple">
<li><p>The <em>method decorator</em> <code class="docutils literal notranslate"><span class="pre">pytch.when_key_pressed</span></code> does the job of a
Scratch <em>hat block</em> — Pytch’s decorators are described in <a class="reference internal" href="hat-blocks.html"><span class="doc">their
own section of the documentation</span></a>.</p></li>
<li><p>The method call <code class="docutils literal notranslate"><span class="pre">self.change_y(10)</span></code> does the job of the <em>change y by</em>
Scratch block — a Pytch sprite’s methods are described below.</p></li>
</ul>
</section>
<section id="controlling-how-a-sprite-looks">
<h2>Controlling how a sprite looks<a class="headerlink" href="#controlling-how-a-sprite-looks" title="Link to this heading">¶</a></h2>
<p>Each sprite can have a collection of <em>Costumes</em> that control how it
looks. The first costume mentioned will be how the sprite first appears
and you can change the Sprite’s appearance using commands.</p>
<p>If a Sprite is to appear on the stage then it has to have at least one
costume (it’s OK for a sprite to be invisible, and then it doesn’t need
to have any costumes at all). Costumes are controlled by a variable in
each Sprite that lists the images that the Sprite can have. To use an
image you have to upload it to your project, and then you can add it to
your Sprite’s list of available Costumes.</p>
<p>You can read the details of how you list costumes in the
<a class="reference internal" href="costume-specs.html#costume-specifications"><span class="std std-ref">assets</span></a> document.</p>
<p>Usually all you have to do is make a list called <em>Costumes</em> in the
sprite and list all the names of the uploaded files you want to use.</p>
<p>This list has to be set up as the Sprite is created (Pytch can’t yet
load more images after the sprite has been set up).</p>
<p>The <em>Costumes</em> variable needs to be declared inside the Sprite. For
example, here is a definition for a new Sprite class that will have two
costumes:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Kitten</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="n">Costumes</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;smiling-kitten.jpg&quot;</span><span class="p">,</span>
                <span class="s2">&quot;frowning-kitten.jpg&quot;</span><span class="p">]</span>
</pre></div>
</div>
<p>By default the Sprite will use the first image as its appearance. If you
want to change to another costume you can use the <code class="docutils literal notranslate"><span class="pre">switch_costume()</span></code>
method.</p>
<dl>
<dt>Setting the sprite size</dt><dd><dl class="py function">
<dt class="sig sig-object py" id="self.set_size">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">set_size</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.set_size" title="Link to this definition">¶</a></dt>
<dd><p>Set how large the sprite appears, as a proportion of the size of the
current costume image, where <code class="docutils literal notranslate"><span class="pre">1</span></code> is the normal size of the image.
For example, <code class="docutils literal notranslate"><span class="pre">self.set_size(0.5)</span></code> will set the sprite to be
half-sized.</p>
</dd></dl>

</dd>
<dt>Finding out the sprite’s size</dt><dd><dl class="py attribute">
<dt class="sig sig-object py" id="self.size">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">size</span></span><a class="headerlink" href="#self.size" title="Link to this definition">¶</a></dt>
<dd><p>The current size of the Sprite, where <code class="docutils literal notranslate"><span class="pre">1</span></code> is normal size,
<code class="docutils literal notranslate"><span class="pre">0.5</span></code> is half-size, <code class="docutils literal notranslate"><span class="pre">2</span></code> is double-size, and so on.</p>
</dd></dl>

</dd>
<dt>Showing and hiding the sprite</dt><dd><dl class="py function">
<dt class="sig sig-object py" id="self.show">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">show</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.show" title="Link to this definition">¶</a></dt>
<dt class="sig sig-object py" id="self.hide">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">hide</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.hide" title="Link to this definition">¶</a></dt>
<dd><p>Make the sprite appear or disappear from the stage. Sprites that are
not showing can still be moved, change costume, and so on but you
won’t see the effect until the sprite is shown again.</p>
</dd></dl>

</dd>
<dt>Changing the sprite appearance</dt><dd><dl class="py function">
<dt class="sig sig-object py" id="self.switch_costume">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">switch_costume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.switch_costume" title="Link to this definition">¶</a></dt>
<dd><p>Select one of the costumes listed in this Sprite’s <em>Costumes</em>
variable. The name is the costume’s <em>label</em>, which is usually the
filename without the extension (see
<a class="reference internal" href="costume-specs.html"><span class="doc">Defining costumes</span></a> for full details). For
example, you might use <code class="docutils literal notranslate"><span class="pre">self.switch_costume(&quot;smiling-kitten&quot;)</span></code> to
choose a new costume.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">switch_costume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">costume_number</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Select one of the costumes listed in this Sprite’s <em>Costumes</em>
variable, by number.  Python starts counting entries in lists <em>at
zero</em>, so to switch to the first costume, you would use
<code class="docutils literal notranslate"><span class="pre">self.switch_costume(0)</span></code>; to switch to the second costume, you would
use <code class="docutils literal notranslate"><span class="pre">self.switch_costume(1)</span></code>, and so on.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.next_costume">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">next_costume</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.next_costume" title="Link to this definition">¶</a></dt>
<dd><p>Switch to the costume after the current one.  If the Sprite is wearing
the last costume in its <code class="docutils literal notranslate"><span class="pre">Costumes</span></code> list, then go back to the first
one in the list.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">next_costume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n_steps</span></span></em><span class="sig-paren">)</span></dt>
<dd><p>Switch to the costume <code class="docutils literal notranslate"><span class="pre">n_steps</span></code> after the current one.  If this
would take the Sprite beyond the end of its <code class="docutils literal notranslate"><span class="pre">Costumes</span></code> list, then
wrap round to the first entry again, as if the costumes were in a
circle.  You can use a negative number for <code class="docutils literal notranslate"><span class="pre">n_steps</span></code> to choose an
<em>earlier</em> costume in the list.  For example, <code class="docutils literal notranslate"><span class="pre">self.next_costume(-1)</span></code>
will switch to the <em>previous</em> costume.</p>
</dd></dl>

</dd>
<dt>Finding out what costume the Sprite is currently wearing</dt><dd><dl class="py attribute">
<dt class="sig sig-object py" id="self.costume_number">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">costume_number</span></span><a class="headerlink" href="#self.costume_number" title="Link to this definition">¶</a></dt>
<dd><p>The <em>zero-based</em> number of the costume currently being worn by the
Sprite.  Here, ‘zero-based’ means that the first costume in the
<code class="docutils literal notranslate"><span class="pre">Costumes</span></code> list is number 0; the second costume is number 1; and so
on.  This is the way that Python refers to list elements.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="self.costume_name">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">costume_name</span></span><a class="headerlink" href="#self.costume_name" title="Link to this definition">¶</a></dt>
<dd><p>The name of the costume currently being worn by the Sprite.</p>
</dd></dl>

</dd>
<dt>Controlling the order Sprites are drawn</dt><dd><p>When one sprite overlaps another it is the order that they are drawn
that controls what you see. Sprites on the back layer are drawn first,
and then Sprites from the next layer are drawn on top of that, and so
on until the front layer is reached. By moving sprites between layers
you can control which Sprites appear on top.</p>
<dl class="py function">
<dt class="sig sig-object py" id="self.go_to_front_layer">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">go_to_front_layer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.go_to_front_layer" title="Link to this definition">¶</a></dt>
<dt class="sig sig-object py" id="self.go_to_back_layer">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">go_to_back_layer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.go_to_back_layer" title="Link to this definition">¶</a></dt>
<dd><p>These methods move a sprite to the very front or the very back of the
layers.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.go_forward_layers">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">go_forward_layers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.go_forward_layers" title="Link to this definition">¶</a></dt>
<dt class="sig sig-object py" id="self.go_backward_layers">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">go_backward_layers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">n</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.go_backward_layers" title="Link to this definition">¶</a></dt>
<dd><p>These methods move a sprite a certain number of layers forward or
backward.</p>
</dd></dl>

</dd>
</dl>
</section>
<section id="moving-a-sprite">
<h2>Moving a Sprite<a class="headerlink" href="#moving-a-sprite" title="Link to this heading">¶</a></h2>
<p>Sprites can move their position on the stage using these motion
commands. There is an exact x and y position on the stage where the
“origin” of the sprite is. Normally the origin in the exact middle of
the sprite’s current costume, but you can change the origin when you are
creating the costume (see
<a class="reference internal" href="costume-specs.html#costume-label-origin-specifications"><span class="std std-ref">here</span></a>)</p>
<dl class="py function">
<dt class="sig sig-object py" id="self.go_to_xy">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">go_to_xy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.go_to_xy" title="Link to this definition">¶</a></dt>
<dd><p>Move the sprite to a particular position on the stage.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.glide_to_xy">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">glide_to_xy</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">y</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">seconds</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.glide_to_xy" title="Link to this definition">¶</a></dt>
<dd><p>Glide the sprite smoothly to a particular position on the stage, taking
the given number of seconds to do so.  The value for <code class="docutils literal notranslate"><span class="pre">seconds</span></code> does
not have to be a whole number.  <em>Advanced/experimental:</em> You can also
give a fourth argument, to give the <em>easing</em> of the glide.  This can
be: the string <code class="docutils literal notranslate"><span class="pre">&quot;linear&quot;</span></code>, to move at a constant speed; or the string
<code class="docutils literal notranslate"><span class="pre">ease-in-out</span></code>, to start slowly, speed up, then slow back down as the
glide finishes.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.change_x">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">change_x</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dx</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.change_x" title="Link to this definition">¶</a></dt>
<dd><p>Change the x-position of the sprite by a certain amount (for example,
<code class="docutils literal notranslate"><span class="pre">self.change_x(10)</span></code> will move the sprite 10 pixels to the right on the
stage). The number of pixels can be negative.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.change_y">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">change_y</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dy</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.change_y" title="Link to this definition">¶</a></dt>
<dd><p>Change the y-position of the sprite by a certain amount (for example,
<code class="docutils literal notranslate"><span class="pre">self.change_y(10)</span></code> will move the sprite 10 pixels up on the
stage). The number can be negative.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.set_x">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">set_x</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">x</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.set_x" title="Link to this definition">¶</a></dt>
<dd><p>Move the sprite to a certain x-position on the stage while keeping its
y-position the same.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.set_y">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">set_y</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">y</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.set_y" title="Link to this definition">¶</a></dt>
<dd><p>Move the sprite to a certain y-position on the stage while keeping its
x-position the same.</p>
</dd></dl>

</section>
<section id="finding-a-sprite-s-position">
<h2>Finding a Sprite’s position<a class="headerlink" href="#finding-a-sprite-s-position" title="Link to this heading">¶</a></h2>
<dl class="py attribute">
<dt class="sig sig-object py" id="self.x_position">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">x_position</span></span><a class="headerlink" href="#self.x_position" title="Link to this definition">¶</a></dt>
<dt class="sig sig-object py" id="self.y_position">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">y_position</span></span><a class="headerlink" href="#self.y_position" title="Link to this definition">¶</a></dt>
<dd><p>The current <em>x</em> or <em>y</em> position of the sprite.  These are
<em>properties</em>, so you do not use <code class="docutils literal notranslate"><span class="pre">()</span></code> after them.</p>
</dd></dl>

</section>
<section id="turning-a-sprite">
<h2>Turning a Sprite<a class="headerlink" href="#turning-a-sprite" title="Link to this heading">¶</a></h2>
<p>A sprite can turn round and point in different directions.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This feature is experimental.  Currently, the <code class="docutils literal notranslate"><span class="pre">touching()</span></code>
results (see <a class="reference internal" href="#collision-detection"><span class="std std-ref">Checking for sprites colliding</span></a>) will be inaccurate if a
sprite has turned from its starting direction.  Also,
<code class="docutils literal notranslate"><span class="pre">when_this_sprite_clicked</span></code> events will not be accurately
detected.</p>
</div>
<dl class="py function">
<dt class="sig sig-object py" id="self.turn_degrees">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">turn_degrees</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">angle</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.turn_degrees" title="Link to this definition">¶</a></dt>
<dd><p>Turn the sprite by the given angle (measured in degrees), in an
anticlockwise (counter-clockwise) direction.  To turn clockwise,
use a negative value for <code class="docutils literal notranslate"><span class="pre">angle</span></code>.  This is the opposite
convention to Scratch, but “positive is anticlockwise” is the
common mathematical convention, so Pytch uses it.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.point_degrees">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">point_degrees</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">angle</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.point_degrees" title="Link to this definition">¶</a></dt>
<dd><p>Turn the sprite so it is pointing in the direction of the given
angle (measured in degrees).  An angle of zero means that the
sprite is drawn the same way up as the original image for the
costume it’s currently wearing.  An angle of 90° means the sprite
points a quarter-turn anticlockwise (counter-clockwise) from its
original image.  To point a quarter-turn clockwise, use −90° (or
270°, which comes to the same thing).</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="self.direction">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">direction</span></span><a class="headerlink" href="#self.direction" title="Link to this definition">¶</a></dt>
<dd><p>The direction the sprite is currently pointing, measured in
degrees.</p>
</dd></dl>

</section>
<section id="making-sounds">
<span id="methods-playing-sounds"></span><h2>Making sounds<a class="headerlink" href="#making-sounds" title="Link to this heading">¶</a></h2>
<p>Sounds have to be loaded into the Sprite when it is created (see
<a class="reference internal" href="sound-specs.html"><span class="doc">Defining sounds</span></a>). Once a sound has been loaded you can get the
sprite to play it.</p>
<dl class="py function">
<dt class="sig sig-object py" id="self.start_sound">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">start_sound</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sound_name_or_index</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.start_sound" title="Link to this definition">¶</a></dt>
<dd><p>Start a sound playing. You refer to the sound in one of two ways.
You can use its <em>label</em>, which is usually the filename without the
extension (see <a class="reference internal" href="sound-specs.html"><span class="doc">Defining sounds</span></a> for full details), or you can use
its <em>index</em>, which is the zero-based position of the required sound
in the Sprite’s list of sounds.  Once the sound has started the
Sprite will move on to its next instruction.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.play_sound_until_done">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">play_sound_until_done</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sound_name_or_index</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.play_sound_until_done" title="Link to this definition">¶</a></dt>
<dd><p>Start a sound playing. You can refer to the sound using its <em>label</em>
or its <em>index</em>, as for <code class="docutils literal notranslate"><span class="pre">start_sound()</span></code>. This method will not
return until the entire sound has played, so the script it is
contained in won’t do its next instruction until then.</p>
</dd></dl>

</section>
<section id="making-and-deleting-copies-of-a-sprite">
<h2>Making and deleting copies of a Sprite<a class="headerlink" href="#making-and-deleting-copies-of-a-sprite" title="Link to this heading">¶</a></h2>
<p>Each Sprite is created on the Stage at the start of the program, but it
is possible to create further copies of each Sprite when the program is
running. These copies are called “clones” of the original.</p>
<p>When a clone is created it starts at the same position and wearing the
same costume as the original, but it can run its own scripts to change
its behaviour. The “self” variable always refers to the <em>current</em> clone.</p>
<section id="creating-new-clones">
<span id="create-clone-of-for-sprites"></span><h3>Creating new clones<a class="headerlink" href="#creating-new-clones" title="Link to this heading">¶</a></h3>
<p>Clones can be created using the <code class="docutils literal notranslate"><span class="pre">pytch.create_clone_of(thing)</span></code>
function:</p>
<dl class="py function">
<dt class="sig sig-object py" id="pytch.create_clone_of">
<span class="sig-prename descclassname"><span class="pre">pytch.</span></span><span class="sig-name descname"><span class="pre">create_clone_of</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">thing</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pytch.create_clone_of" title="Link to this definition">¶</a></dt>
<dd><p>Create a new clone of <code class="docutils literal notranslate"><span class="pre">thing</span></code>.  You can create clones in two ways.
You can clone the original or a copy of one of your Sprites, for example
the copy which is calling the <code class="docutils literal notranslate"><span class="pre">create_clone_of()</span></code> function:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">pytch</span><span class="o">.</span><span class="n">create_clone_of</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span>
</pre></div>
</div>
<p>Or you can create a clone of a particular class of Sprite:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">pytch</span><span class="o">.</span><span class="n">create_clone_of</span><span class="p">(</span><span class="n">Spaceship</span><span class="p">)</span>
</pre></div>
</div>
<p>In this case, Pytch makes a clone of the original instance of that
sprite.</p>
</dd></dl>

</section>
<section id="deleting-clones">
<h3>Deleting clones<a class="headerlink" href="#deleting-clones" title="Link to this heading">¶</a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="self.delete_this_clone">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">delete_this_clone</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#self.delete_this_clone" title="Link to this definition">¶</a></dt>
<dd><p>Remove the current clone. If this method is run by the original sprite
then it has no effect at all.  If it is run by a clone, then the clone
vanishes at the end of the current frame, and execution of the handler
which called <code class="docutils literal notranslate"><span class="pre">delete_this_clone()</span></code> is halted.</p>
</dd></dl>

</section>
<section id="finding-existing-clones">
<h3>Finding existing clones<a class="headerlink" href="#finding-existing-clones" title="Link to this heading">¶</a></h3>
<dl class="py function">
<dt class="sig sig-object py" id="Class.the_original">
<span class="sig-prename descclassname"><span class="pre">Class.</span></span><span class="sig-name descname"><span class="pre">the_original</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Class.the_original" title="Link to this definition">¶</a></dt>
<dd><p>This returns a reference to the <em>original</em> object that this clone is a
copy of. This can be used to look up variables or send messages to the
original object. If it is run by the original Sprite then it returns a
reference to itself. Notice that this method is run using the class name
(for example <code class="docutils literal notranslate"><span class="pre">Kitten.the_original()</span></code>), not the <code class="docutils literal notranslate"><span class="pre">self</span></code> object.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="Class.all_clones">
<span class="sig-prename descclassname"><span class="pre">Class.</span></span><span class="sig-name descname"><span class="pre">all_clones</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Class.all_clones" title="Link to this definition">¶</a></dt>
<dd><p>Returns a list of all the existing clones of the Sprite that is
mentioned (for example <code class="docutils literal notranslate"><span class="pre">Kitten.all_clones()</span></code>). Notice that this method
is run using the class name (for example <code class="docutils literal notranslate"><span class="pre">Kitten.all_clones()</span></code>), not
the <code class="docutils literal notranslate"><span class="pre">self</span></code> object.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="Class.all_instances">
<span class="sig-prename descclassname"><span class="pre">Class.</span></span><span class="sig-name descname"><span class="pre">all_instances</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#Class.all_instances" title="Link to this definition">¶</a></dt>
<dd><p>Like <code class="docutils literal notranslate"><span class="pre">all_clones</span></code>, this returns a list of all clones of the Sprite
that is mentioned (for example <code class="docutils literal notranslate"><span class="pre">Kitten.all_clones()</span></code>), but
<code class="docutils literal notranslate"><span class="pre">all_instances</span></code> also includes the original Sprite in the list. This is
useful if you want access to everything (both clones and
originals). Notice that this method is run using the class name (for
example <code class="docutils literal notranslate"><span class="pre">Kitten.all_instances()</span></code>), not the <code class="docutils literal notranslate"><span class="pre">self</span></code> object.</p>
</dd></dl>

</section>
</section>
<section id="checking-for-sprites-colliding">
<span id="collision-detection"></span><h2>Checking for sprites colliding<a class="headerlink" href="#checking-for-sprites-colliding" title="Link to this heading">¶</a></h2>
<dl class="py function">
<dt class="sig sig-object py" id="self.touching">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">touching</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">target_class</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.touching" title="Link to this definition">¶</a></dt>
<dd><p>You can use this method to check whether this sprite is touching any
instance of another class. For example <code class="docutils literal notranslate"><span class="pre">self.touching(Dog)</span></code> will
return either True or False depending on whether the current Sprite is
overlapping a <code class="docutils literal notranslate"><span class="pre">Dog</span></code> sprite.</p>
<p>At the moment Pytch does not look at the actual image in the costume,
just its overall size, so if the two costumes have blank sections but
the costumes themselves are overlapping then this method will still
return true. The current costume and the size set by <code class="docutils literal notranslate"><span class="pre">set_size</span></code> is
taken into account when checking.</p>
<p>Note that you check using a <em>class</em> name, so if the <code class="docutils literal notranslate"><span class="pre">self</span></code> sprite is
touching any clone of the target class then <code class="docutils literal notranslate"><span class="pre">touching</span></code> will return
true.</p>
</dd></dl>

</section>
<section id="showing-and-hiding-speech-bubbles">
<h2>Showing and hiding speech bubbles<a class="headerlink" href="#showing-and-hiding-speech-bubbles" title="Link to this heading">¶</a></h2>
<p>Speech bubbles can be used to get Sprites to show some text on the
Stage.</p>
<dl class="py function">
<dt class="sig sig-object py" id="self.say">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">say</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">content</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.say" title="Link to this definition">¶</a></dt>
<dd><p>Show a speech bubble next to the current Sprite, showing the text
supplied. For exampler <code class="docutils literal notranslate"><span class="pre">self.say(&quot;Hello</span> <span class="pre">there&quot;)</span></code>.  If the Sprite uses
<code class="docutils literal notranslate"><span class="pre">self.hide()</span></code> to disappear from the stage then the bubble will also
disappear.  If the Sprite then re-appears (by using <code class="docutils literal notranslate"><span class="pre">self.show()</span></code>),
then the speech bubble will also re-appear.</p>
<p>To remove a Sprite’s speech bubble, use the empty string for the
<code class="docutils literal notranslate"><span class="pre">content</span></code> argument, as in:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># Remove speech bubble:</span>
<span class="bp">self</span><span class="o">.</span><span class="n">say</span><span class="p">(</span><span class="s2">&quot;&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="self.say_for_seconds">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">say_for_seconds</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">content</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">seconds</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.say_for_seconds" title="Link to this definition">¶</a></dt>
<dd><p>Show a speech balloon, wait for the number of seconds given, and then
remove it. The whole script will wait while the balloon is being shown.
If a second script calls <code class="docutils literal notranslate"><span class="pre">say_for_seconds()</span></code> while a first script is
already in the middle of <code class="docutils literal notranslate"><span class="pre">say_for_seconds()</span></code>, the second script’s
speech replaces the first script’s speech.</p>
</dd></dl>

</section>
<section id="asking-the-user-a-question">
<span id="sprite-method-ask-and-wait"></span><h2>Asking the user a question<a class="headerlink" href="#asking-the-user-a-question" title="Link to this heading">¶</a></h2>
<p>Pytch has a method matching Scratch’s <em>ask and wait</em> block.  In
Scratch, you can find what the user typed using the <em>answer</em> reporter
block.  In Pytch, the user’s answer is <em>returned</em> to your program from
the <code class="docutils literal notranslate"><span class="pre">ask_and_wait()</span></code> method.</p>
<dl class="py function">
<dt class="sig sig-object py" id="self.ask_and_wait">
<span class="sig-prename descclassname"><span class="pre">self.</span></span><span class="sig-name descname"><span class="pre">ask_and_wait</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">question</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#self.ask_and_wait" title="Link to this definition">¶</a></dt>
<dd><p>Ask the <em>question</em>, and pop up an input box where the user can type
their answer.  If the Sprite is currently shown, the question is
asked with a speech bubble.  If the Sprite is hidden, the question is
asked as part of the input box.</p>
<p>Your method is paused while the user is typing their answer, and will
continue once the user submits their answer.  The answer is returned,
so you will usually assign it to a variable.  For example, this code
assigns the user’s answer to a variable <code class="docutils literal notranslate"><span class="pre">name</span></code> and then greets the
user:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">Banana</span><span class="p">(</span><span class="n">pytch</span><span class="o">.</span><span class="n">Sprite</span><span class="p">):</span>
    <span class="c1"># [ ... Costumes, Sounds, other methods, etc. ... ]</span>
    <span class="nd">@pytch</span><span class="o">.</span><span class="n">when_this_sprite_clicked</span>
    <span class="k">def</span><span class="w"> </span><span class="nf">ask_user_their_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">ask_and_wait</span><span class="p">(</span><span class="s2">&quot;What&#39;s your name?&quot;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">say</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Hello, </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s2">!&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

</section>
</section>


            <div class="clearer"></div>
          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="Main">
        <div class="sphinxsidebarwrapper"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../webapp/user/index.html">Using the Pytch web app</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Writing Pytch programs</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Sprites</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#creating-sprites">Creating Sprites</a></li>
<li class="toctree-l3"><a class="reference internal" href="#saying-how-a-sprite-should-behave">Saying how a sprite should behave</a></li>
<li class="toctree-l3"><a class="reference internal" href="#controlling-how-a-sprite-looks">Controlling how a sprite looks</a></li>
<li class="toctree-l3"><a class="reference internal" href="#moving-a-sprite">Moving a Sprite</a></li>
<li class="toctree-l3"><a class="reference internal" href="#finding-a-sprite-s-position">Finding a Sprite’s position</a></li>
<li class="toctree-l3"><a class="reference internal" href="#turning-a-sprite">Turning a Sprite</a></li>
<li class="toctree-l3"><a class="reference internal" href="#making-sounds">Making sounds</a></li>
<li class="toctree-l3"><a class="reference internal" href="#making-and-deleting-copies-of-a-sprite">Making and deleting copies of a Sprite</a></li>
<li class="toctree-l3"><a class="reference internal" href="#checking-for-sprites-colliding">Checking for sprites colliding</a></li>
<li class="toctree-l3"><a class="reference internal" href="#showing-and-hiding-speech-bubbles">Showing and hiding speech bubbles</a></li>
<li class="toctree-l3"><a class="reference internal" href="#asking-the-user-a-question">Asking the user a question</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="stage.html">The stage</a></li>
<li class="toctree-l2"><a class="reference internal" href="non-hat-blocks.html">Scratch blocks → Pytch functions and methods</a></li>
<li class="toctree-l2"><a class="reference internal" href="pytch-module-functions.html">Functions in the pytch module</a></li>
<li class="toctree-l2"><a class="reference internal" href="hat-blocks.html">Scratch hat blocks → Pytch decorators</a></li>
<li class="toctree-l2"><a class="reference internal" href="costume-specs.html">Defining costumes</a></li>
<li class="toctree-l2"><a class="reference internal" href="backdrop-specs.html">Defining backdrops</a></li>
<li class="toctree-l2"><a class="reference internal" href="sound-specs.html">Defining sounds</a></li>
<li class="toctree-l2"><a class="reference internal" href="multi-threading.html">Running many scripts at once</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About Pytch</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../contact.html">Contact</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../developer.html">Developer documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../legal/index.html">Legal information</a></li>
</ul>
<div class="docs-home-link"><hr>
  <ul>
    <li>
      <a href="../../index.html">Pytch help home</a>
    <li>
  </ul>
</div>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
  </body>
</html>